home *** CD-ROM | disk | FTP | other *** search
/ Online Today 2000 January / Onto0100.iso / mac / MACAST 1.0 / MACAST Documentation / Plugin Development / MACAST_Visual.h < prev   
Encoding:
C/C++ Source or Header  |  1999-09-15  |  12.8 KB  |  360 lines  |  [TEXT/CWIE]
  1. /*
  2.     Visual Plug-in API
  3.     ⌐1999, @soft
  4.     
  5.     Description:    The plugin API for MACAST visual plugins (windowed
  6.                     and full-screen).
  7.     Version:        1.3
  8.     Released:        8/23/99
  9.     Compatibility:    MACAST 1.0
  10.     Version history:
  11.     
  12.      Date    Who        Changes
  13.     ------+------+------------------------------------------------------
  14.     082399    SKA        Added VisListen, and Broadcast callback.
  15.     071199    SKA        Changed a few callbacks, commented the file a little
  16.                     better.
  17.     070899    SKA        Added two new hooks for plugins. 
  18.                     All visual plugins has to be recompiled.
  19.     061999    SKA        Added GetSoundBuffer hook for direct access to sound
  20.                     data
  21.     050299    SKA        Initial release
  22.     043099    SKA        Started the work
  23.  
  24.     SKA = Slava Karpenko
  25. */
  26.  
  27. #pragma once
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. /************************************************************
  33.                     ENUMS AND CONSTANTS
  34. ************************************************************/
  35. #define VP_API_VERSION                0x0120
  36. #define plugVisual                    'VIS!'
  37.  
  38. // Flags for VisInfoBlock.flags
  39. enum {
  40.     vpFlagStartOnLaunch            = 0x0001,        // The plugin will be started on application launch time
  41.     vpFlagHideInMenu            = 0x0002,        // The plugin will not be shown in menu
  42.     
  43.     vpFlagStartOnLaunchMask        = (1L << 0),
  44.     vpFlagHideInMenuMask        = (1L << 1)
  45. };
  46.  
  47. // useful macros to quickly set headers/footers of VPInfoBlock
  48. #define VP_INFOBLOCK_HEADER(a,b) VP_API_VERSION, plugVisual, a, b, nil
  49. #define VP_INFOBLOCK_HEADER_WITH_FLAGS(a,b,c) VP_API_VERSION, plugVisual, a, b, c
  50. #define VP_INFOBLOCK_FOOTER    nil,nil,nil,nil
  51.  
  52. /************************************************************
  53.                     ERRORS & RETURN VALUES
  54. ************************************************************/
  55. enum {
  56.     // Plugin return codes
  57.     errVisNoErr            = noErr,
  58.     errVisTerminate    = 666,            // terminate the plugin
  59.     errVisNoMemory,                    // terminate the plugin and display no memory alert
  60.     
  61.     errVisCustom                    // MACAST will call VisError function and terminate your
  62.                                     //  plugin if you request to.
  63. };
  64.  
  65. /************************************************************
  66.                     FUNCTION DEFINITIONS
  67. ************************************************************/
  68. // Called when the plugin is initialized. You get the FSSpec to the plugin file
  69. // (for opening resfork if you need to). You shall return WindowPtr to your plugin (if you create any).
  70. extern OSStatus    VisInitialize(FSSpecPtr inPlugin, WindowPtr* outWindow, UInt32* ioRefcon);
  71.  
  72. // Called on termination. Plugin should dispose all buffers/structures it had and prepare
  73. // the mind for ethernity. Disposing window is your plugin's responsibility as well.
  74. extern OSStatus    VisTerminate(WindowPtr inWindow, UInt32* ioRefcon);
  75.  
  76. // Called whenever MACAST has some free time. If you're a full-screen plugin, you get this event more often.
  77. extern OSStatus    VisIdle(WindowPtr inWindow, UInt32* ioRefcon);
  78.  
  79. // Display About box or do some about graphic in the plugin window.
  80. extern OSStatus    VisAbout(WindowPtr inWindow, UInt32* ioRefcon);
  81.  
  82. // Draw whatever you want to. Called periodically to ensure steady effect flow.
  83. extern OSStatus VisDraw(WindowPtr inWindow, UInt32* ioRefcon);
  84.  
  85. // This function is called when user clicks in window that is controlled by your plugin.
  86. // You can do what you want with that click.
  87. extern OSStatus VisClick(WindowPtr inWindow, Point inClick, UInt32* ioRefcon);
  88.  
  89. // This function is called when user presses a key. Note that MACAST gets this key as well
  90. // as all other visual plugins.
  91. extern OSStatus VisKeyDown(WindowPtr inWindow, EventRecord* inEvent, UInt32* ioRefcon);
  92.  
  93. // This function is called when window-specific event is posted for your visual plugin.
  94. // If you have this set, it can override VisDraw function, and it is called when MACAST
  95. // wants your plugin to redraw.
  96. extern OSStatus VisMacEvent(WindowPtr inWindow, EventRecord* inEvent, UInt32* ioRefcon);
  97.  
  98. // This function called if you return errVisCustom. You should copy the error string
  99. // and errNum (optionally) and return whether the error is fatal or not. If this function
  100. // returns true, MACAST terminates your plugin, otherwise continues execution.
  101. extern Boolean VisError(StringPtr outErrString, OSStatus* outErrNum);
  102.  
  103. // If you define this function in your gPlugInfo, MACAST will add a corresponding item into
  104. // 'Settings' submenu of plugins menu and will call this function when user chooses it.
  105. // You can display settings dialog, and do whatever you want.
  106. extern OSStatus VisSettings(WindowPtr inWindow, UInt32* ioRefcon);
  107.  
  108. // These functions are called when track in MACAST is started or stopped. You can clear draw area
  109. // etc here. Note that you can also use ma->GetStatus callback to get the current status.
  110. extern OSStatus VisTrackBegin(WindowPtr inWindow, UInt32* ioRefcon);
  111. extern OSStatus VisTrackEnd(WindowPtr inWindow, UInt32* ioRefcon);
  112.  
  113. extern OSStatus VisListen(WindowPtr inWindow, SInt32 inMessage, void* inData, UInt32* ioRefcon);
  114.  
  115. /************************************************************
  116.                     TYPEDEFS AND STRUCTS
  117. ************************************************************/
  118. // ÑPlugin callbacks
  119. typedef OSStatus    (*visInitProcPtr)(FSSpecPtr, WindowPtr*, UInt32*);
  120. typedef OSStatus    (*visGenericProcPtr)(WindowPtr, UInt32*);
  121. typedef OSStatus    (*visClickProcPtr)(WindowPtr, Point, UInt32*);
  122. typedef OSStatus    (*visEventProcPtr)(WindowPtr, EventRecord*, UInt32*);
  123. typedef Boolean     (*visErrorProcPtr)(StringPtr, OSStatus*);
  124. typedef OSStatus    (*visListenProcPtr)(WindowPtr, SInt32, void*, UInt32*);
  125.  
  126. // ÑMACAST Callbacks
  127. //  You can call these anytime you want.
  128.  
  129. typedef void        (*maVisGetValuesArray)(UInt8** outArray, UInt16* outArraySize);
  130. // Get an array of pre-computed values for frequences.
  131. // Every value represents one frequency, and can be in range #0-232.
  132. // Input:
  133. //        none
  134. //    Output:
  135. //        outArray        = pointer to values array
  136. //        outArraySize    = size of the array
  137. //    Returns:
  138. //        nothing
  139.  
  140. typedef void        (*maVisGetFFTArray)(double** outFFT, UInt16* outFFTSize);
  141. // Get FFT array. First half of the array are real parts, second - imaginary.
  142. // Input:
  143. //        none
  144. //    Output:
  145. //        outFFT            = pointer to raw fft array (or nil, if not available)
  146. //        outBufferSize    = size of the array
  147. //    Returns:
  148. //        nothing
  149.  
  150. typedef void        (*maVisGetSoundBuffer)(Ptr* outSoundBuffer, UInt16* outBufferSize);
  151. // Get current sound buffer.
  152. // Input:
  153. //        none
  154. //    Output:
  155. //        outSoundBuffer    = pointer to sound buffer being played (or nil, if no track is playing)
  156. //        outBufferSize    = size of the buffer, in bytes
  157. //    Returns:
  158. //        nothing
  159.  
  160. typedef void        (*maVisGetStatus)(UInt32* outTimer, UInt32* outStatus);
  161. // Get status of thge player (timer, states of repeat, random, sleep etc).
  162. // Input:
  163. //        none
  164. //    Output:
  165. //        outTimer            = timer, in seconds
  166. //        outStatus            = flags field containing status* constants.
  167. //                                (for example, to check if Random mode is set, check for (outStatus & statusRandom))
  168. //    Returns:
  169. //        nothing
  170.  
  171. // Status codes
  172. enum {
  173.     statusRandom    = (1L << 0),
  174.     statusSleep        = (1L << 1),
  175.     statusRepeat    = (1L << 2),
  176.     statusRepeat1    = (1L << 3),
  177.     statusPlaying     = (1L << 4),
  178.     statusPaused    = (1L << 5),
  179.     statusStopped     = (1L << 6)
  180. };
  181.  
  182. typedef OSStatus    (*maVisGetTrackLocationProcPtr)(OSType* outType, Ptr* outData);
  183. // Get current track location.
  184. // Input:
  185. //        none
  186. //    Output:
  187. //        outType            = location type, either locationFile, locationURL or locationNone
  188. //        outData            = location data (depends on outType, see below)
  189. //    Returns:
  190. //        noErr            = lyrics information fetched.
  191. //        resNotFound        = no track is playing at the moment.
  192.  
  193. // Location types
  194. enum {
  195.     locationFile    = 'file',        // outData = FSSpecPtr
  196.     locationURL        = 'url ',        // outData = char* (C string)
  197.     locationNone    = 'none'        // outData = void, does not contains valid data
  198. };
  199.  
  200. typedef OSStatus    (*maVisGetID3InformationProcPtr)(StringPtr outArtist, StringPtr outTitle, StringPtr outAlbum, StringPtr outYear, Ptr* outLyrics);
  201. // Get current track ID3 information.
  202. // Input:
  203. //        none
  204. //    Output:
  205. //        outArtist        = artist
  206. //        outTitle        = title
  207. //        outAlbum        = album (if available, or nil)
  208. //        outYear            = year (if available, or nil)
  209. //        outLyrics        = lyrics (if available, or nil)
  210. //    Returns:
  211. //        noErr            = lyrics information fetched.
  212. //        resNotFound        = no track is playing at the moment.
  213.  
  214. typedef QDGlobalsPtr (*maVisGetQDPtrProcPtr)(void);
  215. // Return the pointer to QD globals (qd->...).
  216. // Input:
  217. //        none
  218. //    Output:
  219. //        none
  220. //    Returns:
  221. //        pointer to qd globals
  222.  
  223. typedef void (*maVisEnterFullScreen)(OSType inAuthorID, OSType inPluginID);
  224. // Notify MACAST of your plugin entering full-screen mode.
  225. // After this call MACAST hides all its windows, and suspends processing other visual plugins
  226. // to ensure maximum CPU time available for your plugin.
  227. // Input:
  228. //        inAuthorID        = author ID as defined in VisInfoBlock structure
  229. //        inPlugID        = plugin ID as defined in VisInfoBlock structure
  230. //    Output:
  231. //        none
  232. //    Returns:
  233. //        nothing
  234. //
  235. // Note: if you pass author/plugin IDs different than defined in your VisInfoBlock, that could cause
  236. // abnormal MACAST behavior.
  237.  
  238. typedef void (*maVisExitFullScreen)(void);
  239. // Notify MACAST of your plugin exiting full-screen mode.
  240. // All previously hidden windows will be shown again, and other visual plugins will get events.
  241. // Input:
  242. //        none
  243. //    Output:
  244. //        none
  245. //    Returns:
  246. //        nothing
  247.  
  248. typedef OSStatus (*maVisSavePrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16 inSize);
  249. // Save plugin-specific preferences in MACAST Data file located in System Folder.
  250. // Input:
  251. //        inAuthorID         = authorID of plugin
  252. //        inPluginID         = pluginID of plugin
  253. //        inBuffer        = pointer to buffer containing preferences chunk to be saved
  254. //        inSize            = size of buffer to be saved
  255. //    Output:
  256. //        none
  257. //    Returns:
  258. //        noErr            = preferences saved successfully.
  259. //        memFullErr        = an unknown, probably memory-related error has occurred.
  260.  
  261. typedef OSStatus (*maVisReadPrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16* ioSize);
  262. // Read plugin-specific preferences you have saved before with SavePrefs hook.
  263. // Input:
  264. //        inAuthorID         = authorID of plugin
  265. //        inPluginID         = pluginID of plugin
  266. //        inBuffer        = pointer to pre-allocated buffer to store preferences
  267. //        ioSize            = size of allocated buffer
  268. //    Output:
  269. //        ioSize            = actual size of preferences
  270. //    Returns:
  271. //        noErr            = preferences read successfully.
  272. //        resNotFound        = unable to find such preferences chunk
  273. //        memFullErr        = size of preferences chunk exceeds size of allocated buffer
  274. //                            (ioSize contains size of preferences chunk)
  275.  
  276. typedef void (*maVisBroadcast)(SInt32 inMessage, void* inData);
  277. // Broadcast MACAST system message to its subsystems. Don't call this unless you know
  278. // what you're doing.
  279. // Input:
  280. //        inMessage         = message id to be broadcasted
  281. //        inData             = data to be broadcasted, or nil
  282. //    Output:
  283. //        none
  284. //    Returns:
  285. //        nothing
  286.  
  287. // Various structures
  288. #pragma options align=power
  289.  
  290. // This is the structure for MACAST callbacks.
  291. typedef struct {
  292.     maVisGetValuesArray                GetValues;
  293.     maVisGetFFTArray                GetFFT;
  294.     maVisGetStatus                    GetStatus;
  295.     maVisGetTrackLocationProcPtr    GetTrackLocation;
  296.     maVisGetID3InformationProcPtr    GetID3Information;
  297.     maVisGetQDPtrProcPtr            GetQDGlobals;
  298.     
  299.     // Full-screen mode
  300.     maVisEnterFullScreen            EnterFullScreen;
  301.     maVisExitFullScreen                ExitFullScreen;
  302.     
  303.     // Storing and reading prefs
  304.     maVisReadPrefs                    ReadPrefs;
  305.     maVisSavePrefs                    SavePrefs;
  306.  
  307.     maVisGetSoundBuffer                GetSoundBuffer;
  308.     
  309.     // New for 1.3
  310.     maVisBroadcast                    Broadcast;
  311. } VPCallbacks, *VPCallbacksPtr;
  312.  
  313. // Main structure for the plugin. Main entry point for the PEF fragment should point to
  314. // a global variable of this type.
  315. typedef struct {
  316.     UInt16    api;                    // API used. Should always contain VP_API_VERSION
  317.     OSType    type;                    // Plugin type. Should be plugVisual.
  318.     
  319.     OSType    authorID;                // Author ID should be registered with @soft to prevent
  320.                                     //  incompatibilities. mailto:devsupport@at-soft.net or
  321.                                     //  mailto:devsupport@MACAST.com
  322.     OSType    pluginID;                // Plugin ID can be anything the author wishes. It is
  323.                                     //  used with author id to store plugin preferences etc
  324.     
  325.     UInt32    flags;                    // Plugin flags
  326.     
  327.     Str255    name;                    // Plugin name (displayed in Plugins menu)
  328.  
  329.     visInitProcPtr            initProc;
  330.     visGenericProcPtr        terminateProc;
  331.     visGenericProcPtr        idleProc;        // set to nil if you don't want to be called at idle time
  332.     visGenericProcPtr        aboutProc;
  333.  
  334.     visGenericProcPtr        drawProc;
  335.     visClickProcPtr            clickProc;
  336.     
  337.     visEventProcPtr            keyDownProc;    // set to nil if you don't want keydowns.
  338.     visEventProcPtr            macEventProc;    // set to nil if you don't want to handle update/click events manually.
  339.     
  340.     visErrorProcPtr            errorProc;
  341.     visGenericProcPtr        settingsProc;    // set to nil if you don't want to be displayed in settings submenu
  342.     visGenericProcPtr        trackBeginProc;
  343.     visGenericProcPtr        trackEndProc;
  344.     
  345.     visListenProcPtr        listenProc;        // set to nil if you don't want internal engine messages
  346.  
  347.     // Set these to nil. They are reserved for future expansion.
  348.     visGenericProcPtr        reservedProc1;
  349.     visGenericProcPtr        reservedProc2;
  350.     visGenericProcPtr        reservedProc3;
  351.         
  352.     // Special APIs (Set to nil, MACAST will set it to the right value)
  353.     VPCallbacksPtr                ma;
  354. } VPInfoBlock, *VPInfoPtr;
  355. #pragma options align=reset
  356.  
  357. #ifdef __cplusplus
  358. }
  359. #endif
  360.